API Reference

load(output_file::AbstractString)

Function to load the results and the model to the hard drive

save(output_file::AbstractString, game_mode<:AbstractCalcMode)

Function to save the Mode element of TheoryOfGames.jl

Auxiliary function to create history rows for iterative solving methods

Auxiliary function to compute the relative tolerance between two quantities x and y

Return the empty set of the coalition

in_core(mode, optimizer; verbose, raw_outputs)

Function to calculte a stable profit distribution that belongs to the core for profit distribution for a game described by the utility function and the grand coalition of player_set.

Inputs

mode : EnumMode Calculation mode: enumerative technique optimizer : Any Optimizer function for the JuMP model used for computation purposes verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status

Outputs

incoredist : Dict Dictionary of the fair distributions of the profits among the players

in_core(mode, optimizer; verbose, ...)

Function to calculte a stable profit distribution that belongs to the core for profit distribution for a game described by the utility function and the grand coalition of player_set.

Inputs

mode : IterMode Calculation mode: enumerative technique optimizer : Any Optimizer function for the JuMP model used for computation purposes verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status

Outputs

incoredist : Dict Dictionary of the fair distributions of the profits among the players

least_core(mode, utilities, optimizer; verbose, raw_outputs)

Function to calculte the least core profit distribution for a game described by the utility function and the grand coalition of player_set.

Inputs

mode : EnumMode Calculation mode: enumerative technique playerset : Vector Vector of the players of the coalition optimizer : Any Optimizer function for the JuMP model used for computation purposes verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status rawoutputs : Bool (optional, default false) When true, it returns all raw outputs

Outputs

leastcore_dist : Dict Dictionary of the fair distributions of the profits among the players

leastcore(mode, playerset, utilities, optimizer; verbose)

Function to calculte the least core profit distribution for a game described by the utility function and the grand coalition of player_set. This function implements an iterative approach by using a column generating approach to iteratively add constraints to the master problem. To do so, the callback function stored in the mode category is exploited

Inputs

mode : IterMode Calculation mode that contains the reference to the callback function that given a profit distribution scheme, returns a tuple of the set of the coalition with the worst profit and its total benefit to be shared callbackworstcoalition accepts one argument (current profit sharing) optimizer : Any Optimizer function for the JuMP model used for computation purposes starttime : (optional, default nothing) Specify the initial time of the method; if nothing the value is initialized by time() rtol : Number (optional, default 1e-2) Relative tolerance of the convergence process atol : Number (optional, default 1e-2) Absolute tolerance of the convergence process lowerbound : Number (optional, default nothing) Lower bound of the variables of the problem (benefit distribution and margin of the worst coalition) upperbound : Number (optional, default nothing) Upper bound of the variables of the problem (benefit distribution and margin of the worst coalition) When nothing, the value is automatically set to the benefit of the grand coalition verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status rawoutputs : Bool (optional, default false) When true, it returns all raw outputs usestartvalue : Bool (optional, default false) When true, in the iterative process the previous iteration value is used as initialization for the followin iteration maxiter : Bool (optional, default 100) Maximum number of iterations of the process preloadcoalitions : Vector (optional, default empty) List of coalitions whose benefit shall be automatically included before the iterative procedure starts bestobjectivestopoption : String (optional, default nothing) Name of the option to stop the lower problem as it reaches a preset value. When this option is nothing, this feature is not used. When this option is non-nothing, in every iteration, a minimum convergence criterion is added so to stop the lower problem as soon as a minimum fesible objective function is reached. This minimum objective value is obtained with respect to the solution of the master problem multiplied by the factor "bestobjectivestoptolerance" If gurobi is used, this option is BestObjStop bestobjectivestoptolerance : Number (optional, default 0.05) Tolerance used in the "bestobjectivestopoption" approach lowerrelaxationstopoption : String (optional, default nothing) Name of the option used to setup the stop criterion of the optimization as soon as the lowest bound reaches the tolerance specified by tolerancelowerrelaxationstop option tolerancelowerrelaxationstop : double (optional, default 0.0) When lowerrelaxationstopoption is enabled, this option specifies the tolerance used to stop the loop

Outputs

profitdistribution Benefit distribution by player minsurplus Benefit of the coalition with the minimum surplus history

nucleolus(mode, utilities; verbose, tol, raw_outputs)

Function to calculte the nucleolus profit distribution for a game described by the utility function and the grand coalition of player_set.

Inputs

mode : EnumMode Calculation mode: enumerative technique optimizer : Any Optimizer function for the JuMP model used for computation purposes verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status tol (optional, default 1e-5) Accepted tolerance for identifying the active constraints in the optimization procedure raw_outputs : Bool (optional, default false) When true, it returns all raw outputs

Outputs

nucleolus_dist : Dict Dictionary of the fair distributions of the profits among the players

Get the total number of coalitions

ref_in_core(mode, ref_dist, optimizer; verbose)

Function to calculte a stable profit distribution that belongs to the core and minimizes the variance of the profit allocation among the players with respect to a pre-defined reward distribution function for a game described by the utility function and the grand coalition of player_set.

Inputs

mode : EnumMode Calculation mode: enumerative technique ref_dist : AbstrctDict Reference distribution by player optimizer : Any Optimizer function for the JuMP model used for computation purposes norm : Any Normalization denominator for every player Default value nothing, hence for every player the Normalization factor is 1.0 verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status

Outputs

specificrefincoredist : Dict Dictionary of the fair distributions of the profits among the players

ref_in_core(mode, ref_dist, optimizer; verbose)

Function to calculte a stable profit distribution that belongs to the core and minimizes the variance of the profit allocation among the players with respect to a pre-defined reward distribution function for a game described by the utility function and the grand coalition of player_set.

Inputs

mode : IterMode Calculation mode: enumerative technique refdist : AbstrctDict Reference distribution by player optimizer : Any Optimizer function for the JuMP model used for computation purposes norm : Any Normalization denominator for every player Default value nothing, hence for every player the Normalization factor is 1.0 numericalmultiplier : Float (default 1e-3) Multiplier to adjust numerical issues verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status

Outputs

specificrefincoredist : Dict Dictionary of the fair distributions of the profits among the players

ref_least_core(mode, ref_dist, optimizer; norm, verbose)

Function to calculte a stable profit distribution that belongs to the least core and minimizes the variance of the profit allocation among the players with respect to a pre-defined reward distribution function for a game described by the utility function and the grand coalition of player_set.

Inputs

mode : AbstractCalcMode Calculation mode: enumerative technique ref_dist : AbstrctDict Reference distribution by player optimizer : Any Optimizer function for the JuMP model used for computation purposes norm (optional, default nothing) Normalization denominator for every player Default value nothing, hence for every player the Normalization factor is 1.0 verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status

Outputs

specificleastcore_dist : Dict Dictionary of the fair distributions of the profits among the players

ref_least_core(mode, ref_dist, optimizer; norm, verbose)

Function to calculte a stable profit distribution that belongs to the least core and minimizes the variance of the profit allocation among the players with respect to a pre-defined reward distribution function for a game described by the utility function and the grand coalition of player_set.

Inputs

mode : AbstractCalcMode Calculation mode: enumerative technique ref_dist : AbstrctDict Reference distribution by player optimizer : Any Optimizer function for the JuMP model used for computation purposes norm (optional, default nothing) Normalization denominator for every player Default value nothing, hence for every player the Normalization factor is 1.0 verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status

Outputs

specificleastcore_dist : Dict Dictionary of the fair distributions of the profits among the players

shapley_value(mode; verbose)

Function to calculte the shapley value for a game described by the utility function and the grand coalition of player_set.

Inputs

mode : EnumMode Calculation mode: enumerative technique verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status

Outputs

shapley_value : Dict Dictionary of the fair distributions of the profits among the players

specific_in_core(mode, dist_objective, optimizer; verbose, raw_outputs)

Function to calculte a stable profit distribution that belongs to the core and maximizes a specific distribution objective specified by distobjective for a game described by the utility function and the grand coalition of playerset.

Inputs

mode : EnumMode Calculation mode: enumerative technique distobjective : Function Function to build the objective function of the profit distribution It shall a function with two arguments, which are the JuMP model and the player set, and it shall build the objective functions using the JuMP @NLobjective or @objective commands optimizer : Any Optimizer function for the JuMP model used for computation purposes verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status rawoutputs : Bool (optional, default false) When true, it returns all raw outputs

Outputs

specificincore_dist : Dict Dictionary of the fair distributions of the profits among the players

specific_in_core(mode, player_set, utilities, optimizer; verbose)

Function to calculte a profit distribution that belongs to the core and maximizes a specific distribution objective specified by distobjective for a game described by the utility function and the grand coalition of playerset. This function implements an iterative approach by using a column generating approach to iteratively add constraints to the master problem. To do so, the callback function stored in the mode category is exploited

Inputs

mode : IterMode Calculation mode that contains the reference to the callback function that given a profit distribution scheme, returns a tuple of the set of the coalition with the worst profit and its total benefit to be shared callbackworstcoalition accepts one argument (current profit sharing) distobjective : Function Function to build the objective function of the profit distribution It shall a function with two arguments, which are the JuMP model and the player set, and it shall build the objective functions using the JuMP @NLobjective or @objective commands optimizer : Any Optimizer function for the JuMP model used for computation purposes starttime : (optional, default nothing) Specify the initial time of the method; if nothing the value is initialized by time() rtol : Number (optional, default 1e-2) Relative tolerance of the convergence process atol : Number (optional, default 1e-2) Absolute tolerance of the convergence process lowerbound : Number (optional, default nothing) Lower bound of the variables of the problem (benefit distribution and margin of the worst coalition) upperbound : Number (optional, default nothing) Upper bound of the variables of the problem (benefit distribution and margin of the worst coalition) When nothing, the value is automatically set to the benefit of the grand coalition verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status rawoutputs : Bool (optional, default false) When true, it returns all raw outputs usestartvalue : Bool (optional, default false) When true, in the iterative process the previous iteration value is used as initialization for the followin iteration maxiter : Bool (optional, default 100) Maximum number of iterations of the process preloadcoalitions : Vector (optional, default empty) List of coalitions whose benefit shall be automatically included before the iterative procedure starts bestobjectivestopoption : String (optional, default nothing) Name of the option to stop the lower problem as it reaches a preset value. When this option is nothing, this feature is not used. When this option is non-nothing, in every iteration, a minimum convergence criterion is added so to stop the lower problem as soon as a minimum fesible objective function is reached. This minimum objective value after which the solver shall return the solution is provided as the option bestobjectivestopvalue If gurobi is used, this option is BestObjStop bestobjectivestopvalue : Number (optional, default -1e-2) Minimum objective function used for the solver to converge When the procedure starts looping lowerrelaxationstopoption : String (optional, default nothing) Name of the option used to setup the stop criterion of the optimization as soon as the lowest bound reaches the tolerance specified by tolerancelowerrelaxationstop option tolerancelowerrelaxationstop : double (optional, default 0.0) When lowerrelaxationstopoption is enabled, this option specifies the tolerance used to stop the loop

Outputs

profitdistribution Benefit distribution by player minsurplus Benefit of the coalition with the minimum surplus history

specific_least_core(mode, dist_objective, optimizer; verbose, raw_outputs)

Function to calculte a stable profit distribution that belongs to the least core and minimizes a specific objective for the profit allocation among the plauers, for a game described by the utility function and the grand coalition of player_set.

Inputs

mode : EnumMode Calculation mode: enumerative technique distobjective : Function Function to build the objective function of the profit distribution, after the least core is obtained It shall be a function with two arguments: the JuMP model of the problem and the player set, and the function shall build the desired objective functions using the JuMP @NLobjective or @objective commands optimizer : Any Optimizer function for the JuMP model used for computation purposes verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status rawoutputs : Bool (optional, default false) When true, it returns all raw outputs

Outputs

specificleastcore_dist : Dict Dictionary of the fair distributions of the profits among the players

specificleastcore(mode, distobjective, playerset, utilities, optimizer; verbose)

Function to calculte the least core profit distribution for a game described by the utility function and the grand coalition of player_set. This function implements an iterative approach by using a column generating approach to iteratively add constraints to the master problem. To do so, the callback function stored in the mode category is exploited

Inputs

mode : IterMode Calculation mode that contains the reference to the callback function that given a profit distribution scheme, returns a tuple of the set of the coalition with the worst profit and its total benefit to be shared callbackworstcoalition accepts one argument (current profit sharing) distobjective : Function Function to build the objective function of the profit distribution, after the least core is obtained It shall be a function with two arguments: the JuMP model of the problem and the player set, and the function shall build the desired objective functions using the JuMP @NLobjective or @objective commands optimizer : Any Optimizer function for the JuMP model used for computation purposes starttime : (optional, default nothing) Specify the initial time of the method; if nothing the value is initialized by time() rtol : Number (optional, default 1e-2) Relative tolerance of the convergence process atol : Number (optional, default 1e-2) Absolute tolerance of the convergence process lowerbound : Number (optional, default nothing) Lower bound of the variables of the problem (benefit distribution and margin of the worst coalition) upperbound : Number (optional, default nothing) Upper bound of the variables of the problem (benefit distribution and margin of the worst coalition) When nothing, the value is automatically set to the benefit of the grand coalition verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status rawoutputs : Bool (optional, default false) When true, it returns all raw outputs usestartvalue : Bool (optional, default false) When true, in the iterative process the previous iteration value is used as initialization for the followin iteration maxiter : Bool (optional, default 100) Maximum number of iterations of the process bestobjectivestopoption : String (optional, default nothing) Name of the option to stop the lower problem as it reaches a preset value. When this option is nothing, this feature is not used. When this option is non-nothing, in every iteration, a minimum convergence criterion is added so to stop the lower problem as soon as a minimum fesible objective function is reached. This minimum objective value is obtained with respect to the solution of the master problem multiplied by the factor "bestobjectivestoptolerance" If gurobi is used, this option is BestObjStop bestobjectivestoptolerance : Number (optional, default 0.05) Tolerance used in the "bestobjectivestopoption" approach lowerrelaxationstopoption : String (optional, default nothing) Name of the option used to setup the stop criterion of the optimization as soon as the lowest bound reaches the tolerance specified by tolerancelowerrelaxationstop option tolerancelowerrelaxationstop : double (optional, default 0.0) When lowerrelaxationstopoption is enabled, this option specifies the tolerance used to stop the loop

Outputs

profitdistribution Benefit distribution by player minsurplus Benefit of the coalition with the minimum surplus history

utility_combs(player_set, utility)

Function to calculate the utility for every combination of players. This table may be used in Game Theory, such as in the calculation of the shapley value. The function iterates all combinations of players in the player_set and execute the utility function to identify the benefits to be shared.

Inputs

player_set : Vector Vector of the players utility : Function Utility function that given any coalition returns the benefit of the coalition It shall be a function utility(::Vector)::T<:Number verbose : Bool When true, it shows a progress bar to describe the current execution status parallel : Bool When true, paralleling is used to compute operations

Outputs

utilities : Dict Dictionary that specifies the utility of each combination of coalition in player_set

Function to get the types of the utility arguments and outputs

var_in_core(mode, optimizer; verbose)

Function to calculte a stable profit distribution that belongs to the core and minimizes the variance of the profit allocation among the plauers for a game described by the utility function and the grand coalition of player_set.

Inputs

mode : EnumMode Calculation mode: enumerative technique optimizer : Any Optimizer function for the JuMP model used for computation purposes verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status

Outputs

var_core : Dict Dictionary of the fair distributions of the profits among the players

var_in_core(mode, optimizer; verbose)

Function to calculte a stable profit distribution that belongs to the core and minimizes the variance of the profit allocation among the plauers for a game described by the utility function and the grand coalition of player_set.

Inputs

mode : IterMode Calculation mode: enumerative technique optimizer : Any Optimizer function for the JuMP model used for computation purposes numerical_multiplier : Float (default 1e-3) Multiplier to adjust numerical issues verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status

Outputs

varincore : Dict Dictionary of the fair distributions of the profits among the players

var_least_core(mode, optimizer; verbose)

Function to calculte a stable profit distribution that belongs to the least core and minimizes the variance of the profit allocation among the players for a game described by the utility function and the grand coalition of player_set.

Inputs

mode : EnumMode Calculation mode: enumerative technique optimizer : Any Optimizer function for the JuMP model used for computation purposes verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status

Outputs

specificleastcore_dist : Dict Dictionary of the fair distributions of the profits among the players

var_least_core(mode, optimizer; verbose)

Function to calculte a stable profit distribution that belongs to the least core and minimizes the variance of the profit allocation among the players for a game described by the utility function and the grand coalition of player_set.

Inputs

mode : EnumMode Calculation mode: enumerative technique optimizer : Any Optimizer function for the JuMP model used for computation purposes numerical_multiplier : Float (default 1e-3) Multiplier to adjust numerical issues verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status

Outputs

specificleastcore_dist : Dict Dictionary of the fair distributions of the profits among the players

verify_in_core(profit_dist, mode, optimizer; verbose, utilities)

Function to calculte whether a given profit distribution belongs to the core. The game shall be described by the utility function and the grand coalition of player_set.

Inputs

mode : EnumMode Calculation mode: enumerative technique optimizer : Any Optimizer function for the JuMP model used for computation purposes verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status

Outputs

incoredist : Dict Dictionary of the fair distributions of the profits among the players

verify_in_core(profit_dist, mode, optimizer; verbose, utilities)

Function to calculte whether a given profit distribution belongs to the core. The game shall be described by the utility function and the grand coalition of player_set.

Inputs

mode : EnumMode Calculation mode: enumerative technique optimizer : Any Optimizer function for the JuMP model used for computation purposes verbose : Bool (optional, default true) When true, it shows a progress bar to describe the current execution status

Outputs

incoredist : Dict Dictionary of the fair distributions of the profits among the players

EnumMode is a structure defining the enumerative representation of the
utilities of a Game

IterMode is a structure defining the modality for interative identification
of the benefit distribution mechanism

Fields

playerset Vector of players callbackbenefitbycoalition : Function Callback function that is used to determine what is the benefit of a coalition and the total benefit of the coalition callbackworstcoalition : Function Callback function that is used to determine what is the coalition with the worst benefit and the total benefit of the coalition. Arguments shall be: - (mandatory) a Dict-like container to describe the current reward distribution by user - kwargs (optional): - modifysolveroptions: vector of pairs to iteratively change the optimization callback to speed up computation time. The implemented callbacks are: 1. bestobjstop: when the bestobjstop callback is used in iterative methods, the corresponding option is updated here depending on the value 2. lowerrelaxationstopoption: option to stop the execution as a lower bound is reached The function shall return a Vector of NamedTuple, where for every entry o shall contain: - leastprofitablecoalition: members of the worst coalition, for result o - coalitionbenefit: benefit of the coalition, for result o - min_surplus: minimum surplus of the coalition, for result o